home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / formats / hdf / hdfs.apb < prev    next >
Text File  |  1980-02-06  |  14KB  |  447 lines
  1.  
  2.  
  3. Appendix  B    Header Files
  4.  
  5.  
  6.  
  7.  
  8. Overview
  9.  
  10. This appendix includes the general header files used in compiling 
  11. all HDF libraries. These files do not  have to be included with most 
  12. applications, but they could be usefully added to code that refers to 
  13. specific tags by name, or code that is designed to be responsive to 
  14. different error conditions. You get these files when you get the 
  15. HDF source code.
  16.  
  17. You will see that the C header (df.h) shown in Figure B.2 is more 
  18. completely commented than the FORTRAN header (dfF.h) shown 
  19. in Figure B.1. So you may want to look at the C header for 
  20. explanations of some definitions, even if you plan to use the 
  21. #define statements from the FORTRAN header.
  22.  
  23. Other headers used for specific applications, such as the RIS 
  24. interface and the SDS interface can be found by obtaining the 
  25. source code from NCSA. They also do not normally have to be 
  26. included with your source code.
  27.  
  28.  
  29.  
  30. Figure B.1  FORTRAN Header File: dfF.h
  31.  
  32. /*****************************************************************************
  33. * 
  34. *                              NCSA HDF version 2.0
  35. *                                December 20, 1988
  36. *
  37. * NCSA HDF Version 2.0 source code and documentation are in the public domain.
  38. * Specifically, we give to the public domain all rights for future licensing
  39. * of the source code, all resale rights, and all publishing rights.
  40. * 
  41. * We ask, but do not require, that the following message be included in all
  42. * derived works:
  43. * 
  44. * Portions developed at the National Center for Supercomputing Applications at
  45. * the University of Illinois at Urbana-Champaign.
  46. * 
  47. * THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE
  48. * SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION,
  49. * WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE
  50. * 
  51. *****************************************************************************/
  52.  
  53. C *-----------------------------------------------------------------------------
  54. C * File:     dfF.h
  55. C * Purpose:    Fortran header file for HDF routines
  56. C * Contents: 
  57. C *    Tag definitions
  58. C * Error return codes
  59. C *    Logical constants
  60. C * Remarks: This file can be included with user programs
  61. C *----------------------------------------------------------------------------*
  62.  
  63. #ifndef DFTAG_NULL
  64.  
  65. #define    DFREF_WILDCARD 0
  66.  
  67. #define    DFTAG_WILDCARD 0
  68. #define    DFTAG_NULL    1
  69.  
  70. #define    DFTAG_FID    100
  71. #define    DFTAG_FD    101
  72. #define    DFTAG_TID    102
  73. #define    DFTAG_TD    103
  74. #define    DFTAG_DIL    104
  75. #define    DFTAG_DIA    105
  76. #define    DFTAG_NT    106
  77. #define    DFTAG_MT    107
  78.  
  79. #define    DFTAG_ID8    200
  80. #define    DFTAG_IP8    201
  81. #define    DFTAG_RI8    202
  82. #define    DFTAG_CI8    203
  83. #define    DFTAG_II8    204
  84.  
  85. #define    DFTAG_ID    300
  86. #define    DFTAG_LUT    301
  87. #define    DFTAG_RI    302
  88. #define    DFTAG_CI    303
  89.  
  90. #define    DFTAG_RIG    306
  91. #define    DFTAG_LD    307
  92. #define    DFTAG_MD    308
  93. #define    DFTAG_MA    309
  94.  
  95. Figure B.1  FORTRAN Header File: dfF.h (Continued)
  96.  
  97. #define    DFTAG_CCN    310
  98. #define    DFTAG_CFM    311
  99. #define    DFTAG_AR    312
  100.  
  101. #define    DFTAG_DRAW    400
  102. #define    DFTAG_RUN    401
  103.  
  104. #define    DFTAG_XYP    500
  105. #define    DFTAG_MTO    501
  106.  
  107. #define    DFTAG_T14    602
  108. #define    DFTAG_T105    603
  109.  
  110. #define    DFTAG_RLE    11
  111. #define    DFTAG_IMCOMP 12
  112.  
  113. C                     Error Return Codes 
  114.  
  115. #define    DFE_NOERROR    0
  116. #define    DFE_FNF    -1
  117. #define    DFE_DENIED    -2
  118. #define    DFE_ALROPEN    -3
  119. #define    DFE_TOOMANY    -4
  120. #define    DFE_BADNAME    -5
  121. #define    DFE_BADACC    -6 
  122. #define    DFE_NOTOPEN    -8
  123. #define    DFE_CANTCLOSE    -9    
  124. #define    DFE_DFNULL    -10    
  125. #define    DFE_ILLTYPE    -11    
  126. #define    DFE_UNSUPPORTED    -12
  127. #define    DFE_BADDDLIST        -13
  128. #define    DFE_NOTDFFILE        -14
  129. #define    DFE_SEEDTWICE        -15
  130. #define    DFE_NOSPACE        -16
  131. #define    DFE_READERROR        -18
  132. #define    DFE_WRITEERROR    -19
  133. #define    DFE_SEEKERROR        -20
  134. #define    DFE_NOFREEDD        -21
  135. #define    DFE_BADTAG        -22
  136. #define    DFE_BADREF        -23
  137. #define    DFE_RDONLY        -24
  138. #define    DFE_BADCALL        -25
  139. #define    DFE_BADPTR        -26
  140. #define    DFE_BADLEN        -27
  141. #define    DFE_BADSEEK        -28
  142. #define    DFE_NOMATCH        -29
  143. #define    DFE_NOTINSET        -30
  144. #define    DFE_BADDIM        -31
  145. #define    DFE_BADOFFSET        -32
  146. #define    DFE_BADSCHEME        -33
  147. #define    DFE_NODIM        -34
  148. #define    DFE_NOTENOUGH        -35
  149.  
  150. C                        Logical Constants
  151.  
  152. #define    DFACC_READ        1
  153. #define    DFACC_WRITE        2
  154. #define    DFACC_CREATE        4
  155. #define    DFACC_ALL        7
  156.  
  157. #endif DFTAG_NULL
  158.  
  159. Figure B.2  C Header File: df.h
  160.  
  161. /*****************************************************************************
  162. * 
  163. *                              NCSA HDF version 2.0
  164. *                                December 20, 1988
  165. *
  166. * NCSA HDF Version 2.0 source code and documentation are in the public domain.
  167. * Specifically, we give to the public domain all rights for future licensing
  168. * of the source code, all resale rights, and all publishing rights.
  169. * 
  170. * We ask, but do not require, that the following message be included in all
  171. * derived works:
  172. * 
  173. * Portions developed at the National Center for Supercomputing Applications at
  174. * the University of Illinois at Urbana-Champaign.
  175. * 
  176. * 
  177. * THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE
  178. * SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION,
  179. * WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE
  180. * 
  181. *****************************************************************************/
  182.  
  183. /*------------------------------------------------------------------------------
  184.  * File:     df.h
  185.  * Purpose:    header file for HDF routines
  186.  * Invokes:    dfi.h
  187.  * Contents: 
  188.  *    Structure definitions: DFddh, DFdd, DFdesc, DFdle, DF, DFdi, DFdata
  189.  *    Procedure type definitions
  190.  *    Global variables
  191.  *    Tag definitions
  192.  *  Error return codes
  193.  *    Logical constants
  194.  * Remarks: This file is included with user programs
  195.  *        Since it includes stdio.h etc., do not include these after df.h
  196.  *----------------------------------------------------------------------------*/
  197.  
  198.  
  199. #ifndef DFTAG_NULL                /* avoid re-inclusion */
  200.  
  201. /* include DF (internal) header information */
  202. #include "dfi.h"
  203.  
  204. /*--------------------------------------------------------------------------*/
  205. /*Type declarations                                 */
  206.  
  207. typedef struct DFddh {        /* format of data descriptor headers as in file */
  208.     int16
  209.         dds;            /* number of dds in header block */
  210.     int32    
  211.         next;            /* offset of next header block */
  212.     } DFddh;
  213.  
  214.         
  215. typedef struct 
  216.     uint16
  217.         tag,            /* data tag */
  218.         ref;            /* data reference number */
  219.     int32
  220.         offset,        /* offset of data element in file */
  221.         length;        /* number of bytes */
  222.     } DFdd;
  223.  
  224. Figure B.2  C Header File: df.h (Continued)
  225.  
  226.     /* descriptor structure is same as dd structure.  ###Note: may be changed */
  227. #define    DFdesc    DFdd
  228.  
  229.  
  230.     /* DLE is the internal structure that stores data descriptor information */
  231.     /* It is a linked list of DDs */
  232. typedef struct DFdle {        /* Data List element */
  233.     struct DFdle
  234.         *next;            /* link to next dle */
  235.     DFddh
  236.         ddh;            /* To store headers */
  237.     DFdd
  238.         dd[1];            /* dummy size */
  239.     } DFdle;    
  240.  
  241.  
  242.     /* DF is the internal structure associated with each DF file */
  243.     /* It holds information associated with the file as a whole */
  244.     /* ### Note: there are hooks for having multiple DF files open at a time */
  245. typedef struct DF {
  246.     DFdle
  247.         *list,        /* Pointer to the DLE list */
  248.         *last_dle;    /* last_dle and last_dd are used in searches to indicate
  249.                     element returned by previous call to DFfind */
  250.     int
  251.         type,        /* 0= not in use, 1= normal, -1 = multiple */
  252.                 /* this is a hook for when multiple files are open */
  253.         access,    /* permitted access types: 0=none, 1=r, 2=w, 3=r/w */
  254.         changed,     /* True if anything in DDs modified since last write */
  255.         last_tag,    /* Last tag searched for by DFfind */
  256.         last_ref,    /* Last reference number searched for */
  257.         last_dd,    /* see last_dle */
  258.         defdds,    /* default number of DD's in each block */
  259.         up_access;    /* access permissions to element being read/updated */
  260.                 /* Used by DFstart */
  261.     DFdd
  262.         *up_dd;    /* DD of element being read/updated, used by DFstart */
  263.                   /* file handle is a file pointer or file descriptor */
  264.                 /* depending whether we use buffered or unbuffered i/o */
  265.  
  266. #ifdef DF_BUFFIO
  267.     FILE *            /* file pointer */
  268. #else DF_BUFFIO
  269.     int            /* file descriptor */
  270. #endif DF_BUFFIO
  271.         file;        /* File handle for real file */
  272. } DF;
  273.  
  274.  
  275. typedef struct DFdi {    /* data identifier: specifies data element uniquely */
  276.     uint16 tag;
  277.     uint16 ref;
  278. } DFdi;
  279.  
  280.  
  281.  
  282. typedef struct DFdata {    /* structure for returning status information */
  283.     int version;        /* version number of program */
  284. } DFdata;
  285.  
  286.  
  287. Figure B.2  C Header File: df.h (Continued)
  288.  
  289. /*--------------------------------------------------------------------------*/
  290. /*        Procedure types                         */
  291.  
  292. DF *DFopen();
  293. int32 DFgetelement();
  294. int32 DFread();
  295. int32 DFseek();
  296. int32 DFwrite();
  297.  
  298. /*--------------------------------------------------------------------------*/
  299. /*        Global Variables                         */
  300.  
  301. #ifndef DFMASTER
  302. extern
  303. #endif DFMASTER
  304. int
  305.     DFerror;            /* Error code for DF routines */
  306.  
  307. /*--------------------------------------------------------------------------*/
  308. /*        Tag Definitions                            */
  309.  
  310. #define    DFREF_WILDCARD 0    /* wildcard ref for searches */
  311.  
  312. #define    DFTAG_WILDCARD 0    /* wildcard tag for searches */
  313. #define    DFTAG_NULL    1        /* empty DD */
  314.  
  315.     /* utility set */
  316. #define    DFTAG_FID    100        /* File identifier */
  317. #define    DFTAG_FD    101        /* File description */
  318. #define    DFTAG_TID    102        /* Tag identifier */
  319. #define    DFTAG_TD    103        /* Tag descriptor */
  320. #define    DFTAG_DIL    104        /* data identifier label */
  321. #define    DFTAG_DIA    105        /* data identifier annotation */
  322. #define    DFTAG_NT    106        /* number type */
  323. #define    DFTAG_MT    107        /* machine type */
  324.  
  325.     /* raster-8 set */
  326. #define    DFTAG_ID8    200        /* 8-bit Image dimension */
  327. #define    DFTAG_IP8    201        /* 8-bit Image palette */
  328. #define    DFTAG_RI8    202        /* Raster-8 image */
  329. #define    DFTAG_CI8    203        /* RLE compressed 8-bit image */
  330. #define    DFTAG_II8    204        /* IMCOMP compressed 8-bit image */
  331.  
  332.     /* Raster Image set */
  333. #define    DFTAG_ID    300        /* Image DimRec */
  334. #define    DFTAG_LUT    301        /* Image Palette */
  335. #define    DFTAG_RI    302        /* Raster Image */
  336. #define    DFTAG_CI    303        /* Compressed Image */
  337.  
  338. #define    DFTAG_RIG    306        /* Raster Image Group */
  339. #define    DFTAG_LD    307        /* Palette DimRec */
  340. #define    DFTAG_MD    308        /* Matte DimRec */
  341. #define    DFTAG_MA    309        /* Matte Data */
  342. #define    DFTAG_CCN    310        /* color correction */
  343. #define    DFTAG_CFM    311        /* color format */
  344. #define    DFTAG_AR    312        /* aspect ratio */
  345.     
  346. #define    DFTAG_DRAW    400        /* Draw these images in sequence */
  347. #define    DFTAG_RUN    401        /* run this as a program/script */
  348.  
  349.  
  350. Figure B.2  C Header File: df.h (Continued)
  351.  
  352. #define    DFTAG_XYP    500        /* x-y position */
  353. #define    DFTAG_MTO    501        /* machine-type override */
  354.  
  355.     /* Tektronix */
  356. #define    DFTAG_T14    602        /* TEK 4014 data */
  357. #define    DFTAG_T105    603        /* TEK 4105 data */
  358.  
  359.     /* Scientific Data set */
  360. #define    DFTAG_SDG    700        /* Scientific Data Group */
  361. #define    DFTAG_SDD    701        /* Scientific Data DimRec */
  362. #define    DFTAG_SD    702        /* Scientific Data */
  363. #define    DFTAG_SDS    703        /* Scales */
  364. #define    DFTAG_SDL    704        /* Labels */
  365. #define    DFTAG_SDU    705        /* Units */
  366. #define    DFTAG_SDF    706        /* Formats */
  367. #define    DFTAG_SDM    707        /* Max/Min */
  368. #define    DFTAG_SDC    708        /* Coord sys */
  369.  
  370.     /* compression schemes */
  371. #define    DFTAG_RLE    11        /* run length encoding */
  372. #define    DFTAG_IMCOMP 12        /* IMCOMP compression */
  373.  
  374. /*--------------------------------------------------------------------------*/
  375. /*        Error Return Codes                         */
  376.  
  377. #define    DFE_NOERROR        0    /* No error */
  378. #define    DFE_FNF        -1    /* File not found error */
  379. #define    DFE_DENIED        -2    /* Access to file denied */
  380. #define    DFE_ALROPEN        -3    /* File already open */
  381. #define    DFE_TOOMANY        -4    /* Too Many DF's or files open */
  382. #define    DFE_BADNAME        -5    /* Bad file name on open */
  383. #define    DFE_BADACC        -6    /* Bad file access mode */
  384. #define    DFE_BADOPEN        -7    /* Other open error */
  385. #define    DFE_NOTOPEN        -8    /* File can't be closed: it isn't open */
  386. #define    DFE_CANTCLOSE        -9    /* fclose wouldn't work! */
  387. #define    DFE_DFNULL        -10    /* DF is a null pointer */
  388. #define    DFE_ILLTYPE        -11    /* DF has an illegal type: internal error */
  389. #define    DFE_UNSUPPORTED    -12    /* Feature not currently supported */
  390. #define    DFE_BADDDLIST        -13    /* No DD list: internal error */
  391. #define    DFE_NOTDFFILE        -14    /* Not a DF file and it is not 0 length */
  392. #define    DFE_SEEDTWICE        -15    /* DD list already seeded: internal error */
  393. #define    DFE_NOSPACE        -16    /* Malloc failed */
  394. #define    DFE_NOSUCHTAG        -17    /* No such tag in the file: search failed*/
  395. #define    DFE_READERROR        -18    /* There was a read error */
  396. #define    DFE_WRITEERROR    -19    /* There was a write error */
  397. #define    DFE_SEEKERROR        -20    /* There was a seek error */
  398. #define    DFE_NOFREEDD        -21    /* No free DD's left: internal error */
  399. #define    DFE_BADTAG        -22    /* illegal WILDCARD tag */
  400. #define    DFE_BADREF        -23    /* illegal WILDCARD reference # */
  401. #define    DFE_RDONLY        -24    /* The DF is read only */
  402. #define    DFE_BADCALL        -25    /* Calls in wrong order */
  403. #define    DFE_BADPTR        -26     /* NULL ptr argument */
  404. #define    DFE_BADLEN        -27    /* negative len specified */
  405. #define    DFE_BADSEEK        -28    /* Attempt to seek past end of element */
  406. #define    DFE_NOMATCH        -29    /* No (more) DDs which match specified tag/ref */
  407. #define    DFE_NOTINSET        -30    /* Warning: Set contained unknown tag: ignored */
  408. #define    DFE_BADDIM        -31    /* negative or zero dimensions specified */
  409. #define    DFE_BADOFFSET        -32    /* Illegal offset specified */
  410. #define    DFE_BADSCHEME        -33    /* Unknown compression scheme specified */
  411. #define    DFE_NODIM        -34    /* No dimension record associated with image */
  412. #define    DFE_NOTENOUGH        -35    /* space provided insufficient for size of data 
  413.  
  414. Figure B.2  C Header File: df.h (Continued)
  415.  
  416. */
  417. #define    DFE_NOVALS        -36    /* Values not available */
  418. #define    DFE_CORRUPT        -37    /* File is corrupted */
  419. #define    DFE_BADCONV        -37    /* Don't know how to convert data type */
  420. #define    DFE_BADFP        -38    /* The file contained an illegal floating point 
  421. no*/
  422.  
  423. /*--------------------------------------------------------------------------*/
  424. /*        Logical Constants                         */
  425.  
  426. #define    DFACC_READ        1    /* Read Access */
  427. #define    DFACC_WRITE        2    /* Write Access */
  428. #define    DFACC_CREATE        4    /* force file to be created */
  429. #define    DFACC_ALL        7    /* logical and of all the above values */
  430.  
  431. #endif DFTAG_NULL
  432.  
  433.  
  434. B.1    NCSA HDF Specifications
  435.  
  436. Header Files    B.1
  437.  
  438. National Center for Supercomputing Applications
  439.  
  440. March 1989
  441.  
  442.                                                                 
  443.  
  444. February 1989
  445.  
  446.  
  447.